
package com.google.api.ads.adwords.jaxws.v201109_1.job;

import java.util.List;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlSeeAlso;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;
import com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJob;
import com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJobSelector;
import com.google.api.ads.adwords.jaxws.v201109_1.cm.JobOperation;
import com.google.api.ads.adwords.jaxws.v201109_1.cm.ObjectFactory;


/**
 * 
 *       Use this service to schedule large batches of updates to
 *       your AdWords campaigns as asynchronous bulk mutate jobs, and to retrieve the
 *       status, results or statistics of your recent jobs.
 *       
 *       <p>For example, a single {@link BulkMutateJob} may contain mutate operations
 *       that update several ad-groups, create several ads, and add thousands of
 *       keywords.</p>
 *       
 *       <p>Each customer has a single job queue - the jobs that operate on the
 *       customer are run one at a time in the order in which they were queued.
 *       <i>Note: Jobs will be rejected (with an {@link ApiException}) once the
 *       customer has 10 pending jobs.</i></p>
 *       
 *       <p>Call {@link #mutate} with an {@code ADD} operation to create a new job
 *       containing the first request part. The service will return the newly created
 *       job with a {@link BulkMutateJobId} for referring to this job in future calls
 *       to the service.</p>
 *       
 *       <p>Call {@link #mutate} with a {@code SET} operation for each additional
 *       request part to be added to this job.</p>
 *       
 *       <p>You may set {@link BulkMutateJob#numRequestParts} for the job during any
 *       of these mutate requests. Failing to set this value will result in the job
 *       remaining in its {@code PENDING} state indefinitely.
 *       
 *       <p><i>Note: Both incomplete and queued jobs have a {@code PENDING} status,
 *       and so both count towards the customer's pending job limit.</i></p>
 *       
 *       <p>Mutate requests to the Bulk Mutate Job Service will fail if the request
 *       was invalid or if any of a job's structural constraints are violated,
 *       and depending on the operation, the job will not get created or updated.</p>
 *       
 *       <p>Once a job has been submitted, you may check its status periodically.
 *       When a job's status changes from {@code PENDING} to {@code PROCESSING}, you
 *       can request the job's processing statistics to be included with the job's
 *       status if you need to track the progress of the job.</p>
 *       
 *       <p class="caution"><b>Caution:</b> Do not do poll the job status too
 *       frequently or you will risk getting your customer rate limited.</p>
 *       
 *       <p>Once a job's status changes to {@code COMPLETED}, you can retrieve the
 *       job's results one part at a time.</p>
 *       
 *       <p>A job can fail even after it has been accepted for processing. For
 *       example, a job may fail at this stage if the total number of operations
 *       exceed the maximum limit for a job even though the number of operations in
 *       each request part did not exceed the maximum limit for a request part. If a
 *       job has a {@code FAILED} status it means that none of its mutate operations
 *       were even processed.</p>
 *       
 *       <p>Once a job is launched in the bulk mutate workflow, the operation streams
 *       in the job are sorted by scoping entity, which is either the customer or the
 *       parent campaign. The operations of a single scoping entity are always
 *       processed in their request order. Operations of different scoping entities
 *       may be processed concurrently or in a different order than in the request.
 *       </p>
 *       
 *       <p>The operations for each scoping entity are processed in batches for
 *       efficiency. Each batch is processed atomically so that either all of them
 *       have successful results, or they all fail with a failure result for the
 *       entire batch.</p>
 *       
 *       <p>The bulk mutate workflow will keep retrying operations when transient
 *       failures occur. However, if these failures persist for several hours or more
 *       serious ones occur, the bulk mutate workflow will abort a job leaving some
 *       or all of its operations unprocessed.</p>
 *     
 * 
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.1.6
 * Generated source version: 2.1
 * 
 */
@WebService(name = "BulkMutateJobServiceInterface", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1")
@XmlSeeAlso({
    ObjectFactory.class
})
public interface BulkMutateJobServiceInterface {


    /**
     * 
     *         Returns a list of bulk mutate jobs.
     *         
     *         @param selector Specifies which jobs to return.
     *         If the selector is empty, all jobs are returned.
     *         @return List of bulk mutate jobs meeting the {@code selector} criteria.
     *         @throws ApiException if problems occurred while fetching the jobs
     *       
     * 
     * @param selector
     * @return
     *     returns java.util.List<com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJob>
     * @throws ApiException
     */
    @WebMethod
    @WebResult(name = "rval", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1")
    @RequestWrapper(localName = "get", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1", className = "com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJobServiceInterfaceget")
    @ResponseWrapper(localName = "getResponse", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1", className = "com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJobServiceInterfacegetResponse")
    public List<BulkMutateJob> get(
        @WebParam(name = "selector", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1")
        BulkMutateJobSelector selector)
        throws ApiException
    ;

    /**
     * 
     *         Adds or updates a bulk mutate job.
     *         
     *         <p>Use the &laquo;ADD&raquo; operator to submit a new job, and the
     *         &laquo;SET&raquo; operator to add additional
     *         {@linkplain BulkMutateRequest request parts} to an existing job.
     *         The &laquo;DELETE&raquo; operator is not supported.
     *         From v201008 and later, use the &laquo;REMOVE&raquo; operator to
     *         cancel a job. Only jobs that still have pending additions of request
     *         parts may be canceled.</p>
     *         
     *         <p class="note"><b>Note:</b> In the current implementation, the check for
     *         duplicate job keys is only "best effort", and may not prevent jobs with
     *         the same keys from being accepted if they are submitted around the same
     *         instant.</p>
     *         
     *         @param operation The operation to perform.
     *         @throws ApiException if problems occurred while creating or updating jobs
     *         @return The added or updated bulk mutate job.
     *       
     * 
     * @param operation
     * @return
     *     returns com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJob
     * @throws ApiException
     */
    @WebMethod
    @WebResult(name = "rval", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1")
    @RequestWrapper(localName = "mutate", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1", className = "com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJobServiceInterfacemutate")
    @ResponseWrapper(localName = "mutateResponse", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1", className = "com.google.api.ads.adwords.jaxws.v201109_1.cm.BulkMutateJobServiceInterfacemutateResponse")
    public BulkMutateJob mutate(
        @WebParam(name = "operation", targetNamespace = "https://adwords.google.com/api/adwords/cm/v201109_1")
        JobOperation operation)
        throws ApiException
    ;

}
